Software information: CreateSEC (self-extracting)

This is a self-extracting code download. Simply download onto a RISC OS system, ensure the filetype is set to ‘Utility’ (&FFC) via the Filer menu and then double-click to run it. The contents will be decompressed into the same directory.

If you wish, you can run from the command line by simply running the file and optionally pass a destination directory as a parameter (to avoid decompressing into the same location as the self-extracting archive). E.g.

*Run $.archive/util $.MyStuff.Decompressed

Further information from the Help file

CreateSEC is a tool for creating “self-extracting code”. The idea is that files, directories and applications can be compressed into a single file (an executable program) which when run will decompress itself without needing any extra programs to be available (such as dearchiving applications).

The CreateSEC tool requires !Routines 1.40 or later, which can be downloaded from http://www.7thsoftware.co.uk/ .

Using the Graphical User Interface

Simply double-click !CreateSEC and it will load onto the iconbar. Select-click the iconbar icon to open the main window. Drag the file, application or directory that you want to compress to the “Input” writable icon.

To specify the output file, you can either type the name into the “Output” writable icon, or you can drag a directory there and then add a suitable leafname. Do not just drag an output directory there because you risk it being replaced by the output file (if you specified “Force”)!

Clicking on “Run” will start the compression process.

If you select the “Verbose” option, the tool will output verbose status information about the compression operation.

If you select the “Force” option, the tool will delete any object found to match the name entered in “Output” before creating the output file with that name. This is intended to be used to force the replacement of a previously generated output file.

Selecting the “No code” option will cause the output to be created without the self-extraction code; just the raw compressed data is output. This is only useful if you intend to use it with a third-party decompression tool.

Some points to note:

• You are not allowed to specify the same object for both the “Input” and “Output” – this would require wiping the input object before the output object can be created!

• You can create output objects with the same leafname as the input object but this has side-effects:
  • For a file, the self-extracting code file will be replaced by the decompressed version when it is run
  • For a directory, attempting to run the self-extracting code file will result in an error (because a directory cannot be created in a location where there is already a file of the same name).
• Both of these issues are not a problem if the user specifies an alternative location to decompress the file to (see below) but in the general case, this should not be relied upon. It is suggested you append the string “util” (or similar) onto the output filename.

Using the Command Line

Self-extracting code can be created as above, but using only the command line.This way is simpler in situations where you do not have a complete !System installed (because the GUI front end for CreateSEC requires some modules which you may not have access to). However, it still requires !Routines to have been ‘seen’ by the Filer.

• Simply ensure that the Filer has ‘seen’ the !CreateSEC application – if you are reading this !Help file, then it almost certainly has already!
• Press ctrl-F12 to open a task window (or just F12 to drop to the shell)
• Type this command (followed by ‘return’):

*CreateSEC <input> <output>

• where <input> is the name of the file, application or directory that you want to compress and <output> is the name of the self-extracting code file that you want to create. For example, you could just do:

*CreateSEC $.!MyApp $.MyApp/util

• You can use the -v switch to enable useful verbose output
• The -f switch can be added to cause any pre-existing output object to be wiped. Use with caution!
• Add the -n switch to build a data-only archive (without the self-extraction code)
• If you dropped to the shell, press return a couple of times to return to the desktop

How to Decompress the Output File

The simple way to decompress the self-extracting code file is to first ensure it has the correct filetype. It should be type “Utility” (&FFC). This can be checked and set from the Filer menu or command line.

Next, simply double-click the file to run it. An hourglass may appear as the decompression process is underway. When complete, the decompressed contents of the file will have been placed into the same directory as the file you ran.

You can also decompress these files from the command line simply by running them in the normal way. If you pass a directory as a parameter (the first and only parameter) to the file, it will decompress into that location rather than the same directory as itself.

Squashed Data File Format

The data appended onto the end of the self-extracting program is stored in the ROOL Squash data format (“rsqs”). This has been designed specifically to make it simple to both create and decompress these data structures, which are able to hold information about RISC OS files and directories.

As the self-extracting code is implemented as a transient utility, the format of the code will look like the following:

  0..23 RISCOS Ltd 32-bit header
  24    Offset to start of the compressed data structure (described below)
  28..  ARM code for the self-extraction routine

Note that the word at offset 24 can be used by 3rd party extractor tools to locate the start of the compressed data and skip over the self-extraction code which is probably of no interest.

In a little more detail, the 32-bit header looks like this:

  0     Branch instruction to start of ARM code
  4     &79766748 = "Hgvy"  }
  8     &216C6776 = "vgl!"  } these two words are ROT13("Utility!")
  12    total size of utility and data (bytes)
  16    0
  20    32

The appended data is stored in the following format (note: the size of this data is included in the calculation of the total size of the utility):

  one (header block, must be at start of data)
  zero or more of either:
    filename block followed by filedata block
  or:
    filename block followed by dirdata block

HEADER BLOCK

  0     "rsqs"
  4     offset to next block (bytes from byte following this word)
  8..   zero or more extension words (undefined bits should be zero)

FILENAME BLOCK

  0     "rnam"
  4     offset to end of block (bytes from byte following this word)
  8     file name (zero terminated, pad with zeros to word boundary)
  n..   zero or more extension words (undefined bits should be zero)

FILEDATA BLOCK

  0     "rdat"
  4     offset to end of block (bytes from byte following this word)
  8     load address
  12    exec address
  16    attributes
  20    squashed data size (bytes)
  24    uncompressed data size (bytes)
  28..  data (pad with zeros to word boundary)

DIRDATA BLOCK

  0     "rdir"
  4     offset to end of block (bytes from byte following this word)
  8     attributes
  12    zero or more extension words (undefined bits should be zero)

File format notes:

• Directories must be defined before the files within are defined.
• Unknown block types or out of order blocks are ignored.
• Assumes 32 bit, little endian word